﻿ #region Disclaimer/Info
 
 /////////////////////////////////////////////////////////////////////////////////////////////////
 //
 //   File:		ICategoryService.cs
 //   Website:		http://dexterblogengine.com/
 //   Authors:		http://dexterblogengine.com/About.ashx
 //   Rev:		1
 //   Created:		19/01/2011
 //   Last edit:		19/01/2011
 //   License:		GNU Library General Public License (LGPL)
 //   File:            ICategoryService.cs
 //   For updated news and information please visit http://dexterblogengine.com/
 //   Dexter is hosted to Codeplex at http://dexterblogengine.codeplex.com
 //   For any question contact info@dexterblogengine.com
 //
 ///////////////////////////////////////////////////////////////////////////////////////////////////
 
 #endregion
 

using System;
using System.Collections.Generic;
using System.ComponentModel;
using Dexter.Core.EventArgs;
using Dexter.DataTransferObject;
using Dexter.Domain.Model;

namespace Dexter.Services
{
	/// <summary>
	/// 	Rapresents the gateway for all service to save, retrieve and manipulate data for <see cref="Category"/>.
	/// </summary>
	public interface ICategoryService {

		/// <summary>
		/// 	Gets the default category with child and parent.
		/// </summary>
		/// <returns>An instance of Category with all tree loaded</returns>
		Category GetDefaultCategoryWithChilds ( );

		/// <summary>
		/// 	Gets the default category with child and parent.
		/// </summary>
		/// <returns>An instance of Category with all tree loaded</returns>
		CategoryDto GetDefaultCategoryDtoWithChilds ( );

		///<summary>
		///	Retrieve a Category by its name.
		///</summary>
		///<param name = "key">The key.</param>
		///<returns>
		///	Null if there isn't a category wich specified name, otherwise an instance of Category.
		///	The Parent and Childs are not fetched.
		///</returns>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="key"/> is lesser than 0.</exception>
		Category GetCategoryByKeyWithChilds(int key);

		///<summary>
		///	Retrieve a Category by its name.
		///</summary>
		///<param name = "key">The key.</param>
		///<returns>
		///	Null if there isn't a category wich specified name, otherwise an instance of Category.
		///	The Parent and Childs are not fetched.
		///</returns>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="key"/> is lesser than 0.</exception>
		CategoryDto GetCategoryDtoByKeyWithChilds ( int key );

		///<summary>
		///	Retrieve a Category by its name.
		///</summary>
		///<param name = "name">The name of the category.</param>
		///<returns>
		///	Null if there isn't a category wich specified name, otherwise an instance of Category.
		///	The Parent and Childs are not fetched.
		///</returns>
		Category GetCategoryByNameWithChilds ( string name );

		///<summary>
		///	Retrieve a Category by its name.
		///</summary>
		///<param name = "name">The name of the category.</param>
		///<returns>
		///	Null if there isn't a category wich specified name, otherwise an instance of Category.
		///	The Parent and Childs are not fetched.
		///</returns>
		CategoryDto GetCategoryDtoByNameWithChilds ( string name );

		/// <summary>
		/// 	Deletes the specified category and moved the into into another.
		/// </summary>
		/// <param name = "category">The category to delete.</param>
		/// <param name = "newCategory">The new category for the posts of the old category.</param>
		void DeleteCategory(Category category, Category newCategory);

		/// <summary>
		/// 	Saves the specified category.
		/// </summary>
		/// <param name="category">The category to save.</param>
		void Save(Category category);

		/// <summary>
		/// 	Updates the specified category.
		/// </summary>
		/// <param name = "category">The category to update.</param>
		void Update(Category category);

		/// <summary>
		/// Updates the category statistics.
		/// </summary>
		void UpdateCategoryStatistics ( );

		///<summary>
		///	Retrurn a flat views of all root categories from the repository.
		///</summary>
		///<returns>
		///	The return value will never be null, there is always the default category.
		///	The tree il completely loaded.
		///</returns>
		IEnumerable<Category> GetCategoriesStructure();

		///<summary>
		///	Retrurn a flat views of all root categories from the repository.
		///</summary>
		///<returns>
		///	The return value will never be null, there is always the default category.
		///	The tree il completely loaded.
		///</returns>
		IList<CategoryDto> GetCategoriesDtoStructure();

		///<summary>
		///	Retrurn a flat views of all categories from the repository.
		///</summary>
		/// <remarks>
		///		The returned objects will not have the tracking system enabled!
		/// </remarks>
		///<returns>
		///	The return value will never be null, there is always the default category.
		///	The tree il completely loaded.
		///</returns>
		IEnumerable<Category> GetAllCategories();

		/// <summary>
		/// This event will raise when the default <see cref="Category"/> will be retrieved by the implementation of <see cref="ICategoryService.GetDefaultCategoryWithChilds()"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<Category>> DefaultCategoryRetrieved;

		/// <summary>
		/// This event will raise before a <see cref="Category"/> will retrieved by the implementation of <see cref="GetCategoryByKeyWithChilds(int, bool)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<Category>> CategoryRetrieved;

		/// <summary>
		/// This event will raise before a <see cref="Category"/> will retrieved by the implementation of <see cref="GetCategoryByNameWithChilds(string)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<Category>> CategoryRetrievedByName;

		/// <summary>
		/// This event will raise when a <see cref="Category"/> will be retrieved by the implementation of <see cref="GetCategoryByKeyWithChilds(int, bool)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<IEnumerable<Category>>> CategoriesRetrieved;

		/// <summary>
		/// This event will raise before a <see cref="Category"/> will deleted by the implementation of <see cref="DeleteCategory(Category, Category)"/>.
		/// </summary>
		event EventHandler<CancelEventArgs> CategoryDeleting;

		/// <summary>
		/// This event will raise when a <see cref="Category"/> will be deleted by the implementation of <see cref="DeleteCategory(Category, Category)"/>.
		/// </summary>
		event EventHandler<System.EventArgs> CategoryDeleted;

		/// <summary>
		/// This event will raise before a <see cref="Category"/> will deleted by the implementation of <see cref="Save(Category)"/>.
		/// </summary>
		event EventHandler<CancelEventArgs> CategorySaving;

		/// <summary>
		/// This event will raise when a <see cref="Category"/> will be deleted by the implementation of <see cref="Save(Category)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<Category>> CategorySaved;

		/// <summary>
		/// This event will raise before a <see cref="Category"/> will updated by the implementation of <see cref="Update(Category)"/>.
		/// </summary>
		event EventHandler<CancelEventArgs> CategoryUpdating;
		
		/// <summary>
		/// This event will raise when a <see cref="Category"/> will be updated by the implementation of <see cref="Update(Category)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<Category>> CategoryUpdated;
	}
}
